Skip to main content
Developers Repository

National Communication Register (EMEp)

This document describes how to consume the SOAP Web Service of the National Communication Register (EMEp). It focuses specifically on the method getNncIdentity, which retrieves a citizen’s residence and communication information based on their Tax Identification Number (TIN). The document includes the required parameters, response structure, authentication details, and usage examples needed to successfully integrate and utilize the service.

Functionality Description​

The getNncIdentity method provides the ability to return the residence and communication details of a citizen from the National Communication Register (EMEp), based on the citizen's Tax Identification Number (TIN).

The information is returned only if the citizen has confirmed their details via the EMEP platform

Parameters​

A. Service endpoint URLs

B. Client application authentication details

Every call to the endpoint must also include the client's authentication details, which consist of the username and password.
The authentication details are inserted into the SOAP header, as shown below:

<soapenv:Header>
    <wsse:Security soapenv:mustUnderstand="1"
                   xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsse:UsernameToken wsu:Id="UsernameToken-1">
            <wsse:Username>******</wsse:Username>
            <wsse:Password
                    Type='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'>
                *******
            </wsse:Password>
        </wsse:UsernameToken>
    </wsse:Security>
</soapenv:Header>

C. Audit record

Every call must also include the Audit Record information. The Audit Record is a call logging mechanism that must be sent with every call to the Web Services of the General Secretariat for Information Systems and Digital Governance (https://www.gsis.gr/dimosia-dioikisi/kentro-dialeitoyrgikotitas-ked-ypoyrgeioy-psifiakis-diakybernisis/koinos-odigos).

Structure of getNncIdentity Call​

Audit Record Structure​

The auditRecord includes the following fields:

  • auditTransactionId: alphanumeric – identifier or call serial number of the endpoint (e.g., "1", "2", etc.)
  • auditTransactionDate: date and time in the format yyyy-mm-ddThh:mm:ssZ – the date and time of the call (e.g., " 2025-04-28T10:08:24Z")
  • auditProtocol: alphanumeric – protocol number to provide a reference for the log entry of the call (e.g., "1123")
  • auditUnit: alphanumeric – description of the business unit from which the call is made (e.g., "DEDDE")
  • auditUserId: alphanumeric – user ID number (e.g., "1123")
  • auditUserIp: alphanumeric – IP address number of the user (e.g., "0.0.0.0")

Example of getNncIdentity Call​

The call is made with a POST request to one of the Service endpoint URLs and the payload body should be in XML format, as shown below:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:not="http://gsis.ggps.interoperability/notificationCenterElementsInterface">
    <soapenv:Header>
        <wsse:Security soapenv:mustUnderstand="1"
                       xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                       xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:UsernameToken wsu:Id="UsernameToken-1">
                <wsse:Username>******</wsse:Username>
                <wsse:Password
                        Type='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText'>
                    *******
                </wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
    <soapenv:Body>
        <not:getNncIdentityRequest>
            <auditRecord>
                <auditTransactionId>1</auditTransactionId>
                <auditTransactionDate>2025-03-20T18:20:55Z</auditTransactionDate>
                <auditProtocol>1</auditProtocol>
                <auditUnit>AGENCY</auditUnit>
                <auditUserId>user</auditUserId>
                <auditUserIp>0.0.0.0</auditUserIp>
            </auditRecord>
            <getNncIdentityInputRecord>
                <afm>********</afm>
            </getNncIdentityInputRecord>
        </not:getNncIdentityRequest>
    </soapenv:Body>
</soapenv:Envelope>

Example response to the above call:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:getNncIdentityResponse xmlns:ns2="http://gsis.ggps.interoperability/notificationCenterElementsInterface">
            <getNncIdentityOutputRecord>
                <countryCode>GRC</countryCode>
                <countryDescr>Ελλάδα</countryDescr>
                <addressStreet>Δωδώνης</addressStreet>
                <addressNumber>**</addressNumber>
                <addressCity>Αθήνα</addressCity>
                <telephone>210***</telephone>
                <countryCode2>GRC</countryCode2>
                <countryDescr2>Ελλάδα</countryDescr2>
                <addressStreet2>Δωδώνης</addressStreet2>
                <addressNumber2>**</addressNumber2>
                <addressCity2>Αθήνα</addressCity2>
                <mobile>697***</mobile>
                <email>***</email>
                <epikForeisFlag>1</epikForeisFlag>
                <epidForeisFlag>0</epidForeisFlag>
            </getNncIdentityOutputRecord>
            <callSequenceId>10025109238</callSequenceId>
            <callSequenceDate>2025-05-21T10:26:01.817+03:00</callSequenceDate>
            <errorRecord/>
        </ns2:getNncIdentityResponse>
    </soap:Body>
</soap:Envelope>

Error responses during the call​

In case of an error during the Web Service call, the error code and message are returned in the response, which are described below:

Error Code NameError Description
GEN_AUDIT_VALIDATION_INV_DATA_OR_UNAUTH_OPERThe username and password used in the Soap Header during the call are not authorized to use the specific function (e.g., getNncIdentity)
GEN_AUDIT_VALIDATION_INVALID_AUDIT_DATAAn error occurred during the validation of the call's audit fields.
GEN_INVALID_DATAAn error occurred during the validation check of the service's input fields (e.g., the TIN was not provided).
GEN_COMMUNICATION_ERRORAn error occurred during communication with the web service of the external agency (requires contacting Technical Support of the external agency)
GEN_DATABASE_CONNECTION_ERRORAn error occurred while connecting to the Database (requires contacting the Interoperability Center of the Ministry of Digital Governance KED Technical Support)
GEN_GENERAL_ERRORAn unspecified error occurred (requires contacting the Interoperability Center of the Ministry of Digital Governance KED Technical Support)
GEN_AUTHORIZATION_MAX_OPEN_CALLS_EXCEEDEDThe daily call limit has been exceeded

Calling the Service using Python​

To call getNncIdentity with Python, the Python Requests and xmltodict libraries can be used. Python Requests is used to make the call, and xmltodict is used to parse the response into a Python dictionary format, so that the information can be easily processed.

The call with Python Requests can be as follows:

response = requests.post(url=endpoint_url, data=xml)

Where:

  • endpoint_url is one of the endpoints as defined in the Parameters section
  • xml is the call information data as in the previous example in xml format

Using xmltodict, we can get the response in a dictionary format as follows:

response_dict = xmltodict.parse(response_text)

Where:

  • response_text is the response from Python Requests library in string format
We'd love your feedback
Was this helpful?